home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.017 < prev    next >
Encoding:
Text File  |  1988-12-16  |  5.2 KB  |  111 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIGS
  8. #17:    Application Memory Management and the MMStartUp User ID
  9.  
  10. Revised by:    Steven Glass & Rich Williams                     November 1988
  11. Written by:    Jim Merritt                                          June 1987
  12.  
  13. This Technical Note describes a technique which permits an application to 
  14. dispose of any memory it has used with a single Memory Manager call without 
  15. clobbering other system components or itself.
  16. _____________________________________________________________________________
  17.  
  18.  
  19. Ground Rules for Application Memory Usage
  20.  
  21. Apple IIGS programs must be responsible for allocating and disposing of any 
  22. memory they use, over and above that which the operating system itself gives 
  23. them.  In general, no IIGS program should use any memory except that which the 
  24. Memory Manager has explicitly granted to it.  A program may request additional 
  25. memory for its own use at any time with one or more calls to the NewHandle 
  26. routine.  At program termination, the application is responsible for 
  27. explicitly disposing of any memory that it explicitly acquired, and if it 
  28. fails to do so, it could leave the IIGS memory management system in a 
  29. corrupted state.
  30.  
  31. You may dispose of memory on a handle-by-handle basis, or you may dispose of 
  32. it en masse by calling DisposeAll, but you should never use DisposeAll with 
  33. the user ID that the MMStartUp routine provides.  This user ID is the "master 
  34. user ID" for the application, and it tags the memory space which the operating 
  35. system reserves for the program's code and static data at load time.  Calling 
  36. DisposeAll with this user ID results in immediate deallocation of the memory 
  37. in which the calling program resides; therefore, an application which 
  38. allocates dynamic data space using only the user ID that MMStartUp gives it 
  39. should not use DisposeAll to deallocate that space, but rather use 
  40. DisposeHandle to deallocate it handle by handle.
  41.  
  42.  
  43. Cleaning Up With DisposeAll
  44.  
  45. It is possible, however, for a program to use a different, unique user ID when 
  46. allocating its own RAM, then pass that user ID to DisposeAll when it 
  47. terminates to deallocate all of its private memory at once without endangering 
  48. itself or other parts of the IIGS system.  With this technique, the question 
  49. is how best to acquire a new user ID?  One method to acquire a new user ID is 
  50. to request a completely new one of the appropriate type from the User ID 
  51. Manager in the Miscellaneous Tools.  In this case, when the application 
  52. terminates, it must not only deallocate the memory it used, but also the 
  53. additional user ID which it requested from the User ID Manager.
  54.  
  55. Actually, it is not necessary for a program to acquire a completely new user 
  56. ID to use DisposeAll without clobbering itself.  Instead, the application may 
  57. modify the auxID field of the master user ID which MMStartUp assigns to create 
  58. a unique user ID for allocating its own memory. The 16-bit user ID contains 
  59. the auxID field in bits $8 - $B.  The value of this field, which may range 
  60. from $0 to $F, is always zero in the application's master user ID, but you can 
  61. fill it with any non-zero value to create up to 15 new and distinct user IDs, 
  62. each of which you can pass to NewHandle to allocate memory.and to DisposeAll 
  63. to deallocate memory without endangering the memory tagged by the master user 
  64. ID.  The following assembly code fragment illustrates this technique:
  65.  
  66.     ; assumes full native mode
  67.            pushword #0              ; room for user ID
  68.            _MMStartUp
  69.            pla                      ; master user ID
  70.            sta MasterID
  71.            ora  #$0100              ; auxID:= 1
  72.  
  73.     ;    (COULD HAVE BEEN ANYTHING FROM $1 to $F)
  74.  
  75.            sta MyID                 ; use this to allocate private memory
  76.            ...
  77.            etc.
  78.            ...
  79.  
  80.     ; ready to exit program
  81.            pushword MyID
  82.            _DisposeAll              ; dumps only my own RAM
  83.  
  84. ; now do any remaining processing related to termination
  85.  
  86. You do not need to explicitly deallocate any user ID that you derive by 
  87. changing the auxID field of a valid master user ID.  When the system (usually 
  88. the one to deallocate the master) deallocates the master user ID, it also 
  89. deallocates its derivatives.
  90.  
  91.  
  92. One Word of Caution
  93.  
  94. Several of the Memory Manager's "All" calls (e.g., DisposeAll) treat a zeroed 
  95. auxID field as a wildcard which matches any value that the field may contain, 
  96. thus if you call DisposeAll with the application's master user ID (where the 
  97. auxID field is zero), the Memory Manager will not only deallocate all memory 
  98. belonging to the master user ID, but also all handles and memory segments that 
  99. are associated with user IDs which are derived from that master.  The 
  100. operating system's QUIT mechanism typically executes such a call when cleaning 
  101. up after a normal (i.e., non-restartable) application to keep the memory 
  102. management system from clogging.  This action is purely a defensive measure, 
  103. and well-behaved applications - particularly restartable ones - should dispose 
  104. of their own memory and never rely upon the operating system to clean up after 
  105. them.
  106.  
  107.  
  108. Further Reference
  109. o    Apple IIGS Toolbox Reference, Volume 1
  110.  
  111.